Summary

Finally bringing semantic search to reality!
This PR integrates a FAISS-backed semantic search service using BGE (BAAI General Embedding) models (based on Jacky’s work from last semester), along with backend proxy endpoints and updated catalog UX, enabling AI course search.

⚠️ IMPORTANT: Remember to add SEMANTIC_SEARCH_URL=http://semantic-search:8000 to your .env!

⚠️ IMPORTANT: First-time index building may take 2-3 minutes. In the future, index building will automatically trigger when running the datapuller.
Please run the commands below and modify the semester to build the index first!

curl -X POST http://localhost:8000/refresh \
       -H 'Content-Type: application/json' \
       -d '{"year": 2026, "semester": "Spring"}' | jq

System Architecture

flowchart LR

    %% ---------- Frontend ----------
    subgraph Frontend
        FE_UI["Search Bar + AI Search Toggle"]
    end

    %% ---------- Node Backend ----------
    subgraph NodeBackend
        ProxyRouter["/api/semantic-search/*  (proxy router)"]
        CoursesAPI["/api/semantic-search/courses  (lightweight endpoint)"]
        GraphQLResolvers["GraphQL resolvers + hasCatalogData"]
    end

    %% ---------- Python Semantic Service ----------
    subgraph SemanticService["Semantic Search Service (FastAPI)"]
        Health["/health"]
        Refresh["/refresh  (rebuild FAISS index)"]
        Search["/search  (threshold-based semantic query)"]
        BGE["BGE Embedding Model"]
        FAISS["FAISS Index (cosine similarity)"]
    end

    %% ---------- Catalog Data Puller ----------
    subgraph CatalogData
        DataPuller["GraphQL Catalog Datapuller"]
    end

    %% ---------- Data Flow ----------
    FE_UI -->|Search Query| CoursesAPI

    CoursesAPI -->|Forward to Python| Search

    Search -->|Generate Query Embedding| BGE
    Search -->|Vector Similarity Search| FAISS
    FAISS -->|Threshold-filtered Results| Search

    Search --> CoursesAPI --> FE_UI

    %% Index refresh / data ingestion
    DataPuller --> GraphQLResolvers --> |TODO:|Refresh
    Refresh -->|Fetch Catalog via GraphQL| GraphQLResolvers
    Refresh -->|Generate Embeddings| BGE --> FAISS

Examples

Input: “Memory models in concurrent programming”
→ Should return courses like databases, operating systems, etc.
→ Should not return biology or psychology courses just because of the word “memory.”

Input: “how to shot a hot vlog”

Implementation Details

Python Semantic Search Service (FastAPI)

• FastAPI microservice (apps/semantic-search) that:

  • Uses BGE (BAAI/bge-base-en-v1.5) embedding model optimized for retrieval tasks
  • Builds term-specific embeddings + FAISS indices from GraphQL catalog data
  • Implements threshold-based filtering (returns all results above similarity threshold, not just top-k)
  • Searches top 500 candidates for performance, then filters by threshold (default: 0.45)

• Key endpoints:

  • /health — readiness probe showing index status
  • /refresh — rebuild FAISS index for a given year/semester
  • /search — semantic query with threshold filtering

• Model Architecture:

  • Uses instruction prefix for queries: "Represent this sentence for searching relevant passages: {query}"
  • Course text format: SUBJECT: {subj} NUMBER: {num}\nTITLE: {title}\nDESCRIPTION: {desc}
  • FAISS IndexFlatIP with L2-normalized embeddings (cosine similarity)

Example: manually refreshing an index

curl -X POST http://localhost:8000/refresh \
     -H 'Content-Type: application/json' \
     -d '{"year": 2026, "semester": "Spring"}' | jq

Example: running a semantic search

# Threshold-based search (returns all courses with similarity > 0.45)
curl "http://localhost:8000/search?query=deep%20reinforcement%20learning&year=2026&semester=Spring&threshold=0.45" | jq

# Response includes similarity scores for ranking
{
  "query": "deep reinforcement learning",
  "threshold": 0.45,
  "count": 12,
  "results": [
    {
      "subject": "COMPSCI",
      "courseNumber": "285",
      "score": 0.713,
      "title": "Deep Reinforcement Learning, Decision Making, and Control"
    },
    ...
  ]
}

Backend Integration (Node / Express)

• Added SEMANTIC_SEARCH_URL environment variable pointing to Python service

• Implemented lightweight proxy endpoint /api/semantic-search/courses:

  • Forwards requests to Python service
  • Returns only {subject, courseNumber, score} for efficient frontend filtering
  • Frontend maintains API response order (sorted by semantic similarity)

• Updated GraphQL behavior:

  • Introduced hasCatalogData field for term filtering
  • Updated resolver to use terms(withCatalogData: true)

Frontend (Catalog UI)

• AI Search toggle (✨ sparkle button) to activate semantic search mode
• Semantic results preserve backend ordering (by similarity score)
• Frontend maps semantic results to full course objects for display
• Graceful fallback to fuzzy search when semantic search unavailable

Technical Decisions

Why BGE over other models?

• BGE (BAAI General Embedding) is specifically optimized for retrieval tasks
• Better semantic understanding than general-purpose models (all-MiniLM, mpnet)
• Supports instruction prefixes for improved query understanding
• 109M parameters - good balance of accuracy and speed

Why threshold instead of top-k?

• Threshold-based filtering returns all relevant results, not arbitrary top-k
• More flexible - can return 5 results for specific queries, 50 for broad queries
• Similarity score threshold (0.45) ensures quality over quantity
• Searches top 500 candidates for performance, then applies threshold

Model Options Available (hardcoded in main.py)

# Current: BAAI/bge-base-en-v1.5 (best for retrieval)
# Alternatives:
#   BAAI/bge-small-en-v1.5       (faster, 33M params)
#   BAAI/bge-large-en-v1.5       (most accurate, 335M params)
#   all-mpnet-base-v2            (general purpose, 110M params)
#   all-MiniLM-L6-v2             (fastest, 22M params)

Next Steps

1. Datapuller Integration: TOP PRIORITY!
   Automatically trigger /refresh endpoint when new catalog data is pulled

2. Fine-tuning for Berkeley Courses
   Collect user feedback dataset (query + relevant/irrelevant courses) to fine-tune BGE specifically for Berkeley course search

e. Query Expansion
Handle abbreviations (NLP → Natural Language Processing) and synonyms

Based on: Initial prototype by Jacky (last semester)
Frontend integration: @PineND